<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
	<head>
		<meta http-equiv="content-type" content="text/html; charset=utf-8" />
		<meta name="generator" content="JsDoc Toolkit" />
		
		<title>JsDoc Reference - pv.Scale.linear</title>

		<style type="text/css">
			/* default.css */
body
{
	font: 12px "Lucida Grande", Tahoma, Arial, Helvetica, sans-serif;
	width: 800px;
}

.header
{
	clear: both;
	background-color: #ccc;
	padding: 8px;
}

h1
{
	font-size: 150%;
	font-weight: bold;
	padding: 0;
	margin: 1em 0 0 .3em;
}

hr
{
	border: none 0;
	border-top: 1px solid #7F8FB1;
	height: 1px;
}

pre.code
{
	display: block;
	padding: 8px;
	border: 1px dashed #ccc;
}

#index
{
	margin-top: 24px;
	float: left;
	width: 160px;
	position: absolute;
	left: 8px;
	background-color: #F3F3F3;
	padding: 8px;
}

#content
{
	margin-left: 190px;
	width: 600px;
}

.classList
{
	list-style-type: none;
	padding: 0;
	margin: 0 0 0 8px;
	font-family: arial, sans-serif;
	font-size: 1em;
	overflow: auto;
}

.classList li
{
	padding: 0;
	margin: 0 0 8px 0;
}

.summaryTable { width: 100%; }

h1.classTitle
{
	font-size:170%;
	line-height:130%;
}

h2 { font-size: 110%; }
caption, div.sectionTitle
{
	background-color: #7F8FB1;
	color: #fff;
	font-size:130%;
	text-align: left;
	padding: 2px 6px 2px 6px;
	border: 1px #7F8FB1 solid;
}

div.sectionTitle { margin-bottom: 8px; }
.summaryTable thead { display: none; }

.summaryTable td
{
	vertical-align: top;
	padding: 4px;
	border-bottom: 1px #7F8FB1 solid;
	border-right: 1px #7F8FB1 solid;
}

/*col#summaryAttributes {}*/
.summaryTable td.attributes
{
	border-left: 1px #7F8FB1 solid;
	width: 140px;
	text-align: right;
}

td.attributes, .fixedFont
{
	line-height: 15px;
	color: #002EBE;
	font-family: "Courier New",Courier,monospace;
	font-size: 13px;
}

.summaryTable td.nameDescription
{
	text-align: left;
	font-size: 13px;
	line-height: 15px;
}

.summaryTable td.nameDescription, .description
{
	line-height: 15px;
	padding: 4px;
	padding-left: 4px;
}

pre
{
	border-left: solid 10px #ddd;
	padding-left: 1.5em;
}

.summaryTable { margin-bottom: 8px; }

ul.inheritsList
{
	list-style: square;
	margin-left: 20px;
	padding-left: 0;
}

.detailList {
	margin-left: 20px; 
	line-height: 15px;
}
.detailList dt { margin-left: 20px; }

.detailList .heading
{
	font-weight: bold;
	padding-bottom: 6px;
	margin-left: 0;
}

.light, td.attributes, .light a:link, .light a:visited
{
	color: #777;
	font-style: italic;
}

.fineprint
{
	text-align: right;
	font-size: 10px;
}

		</style>
	</head>

	<body>
<!-- ============================== header ================================= -->	
		<!-- begin static/header.html -->
		<div id="header">
</div>
		<!-- end static/header.html -->

<!-- ============================== classes index ============================ -->
		<div id="index">
			<!-- begin publish.classesIndex -->
			<div align="center"><a href="../index.html">Class Index</a>
| <a href="../files.html">File Index</a></div>
<hr />
<h2>Classes</h2>
<ul class="classList">
	
	<li><i><a href="../symbols/_global_.html">_global_</a></i></li>
	
	<li><a href="../symbols/Array.html">Array</a></li>
	
	<li><a href="../symbols/Date.html">Date</a></li>
	
	<li><a href="../symbols/pv.html">pv</a></li>
	
	<li><a href="../symbols/pv.Anchor.html">pv.Anchor</a></li>
	
	<li><a href="../symbols/pv.Area.html">pv.Area</a></li>
	
	<li><a href="../symbols/pv.Bar.html">pv.Bar</a></li>
	
	<li><a href="../symbols/pv.Color.html">pv.Color</a></li>
	
	<li><a href="../symbols/pv.Color.Hsl.html">pv.Color.Hsl</a></li>
	
	<li><a href="../symbols/pv.Color.Rgb.html">pv.Color.Rgb</a></li>
	
	<li><a href="../symbols/pv.Colors.html">pv.Colors</a></li>
	
	<li><a href="../symbols/pv.Dot.html">pv.Dot</a></li>
	
	<li><a href="../symbols/pv.Flatten.html">pv.Flatten</a></li>
	
	<li><a href="../symbols/pv.Image.html">pv.Image</a></li>
	
	<li><a href="../symbols/pv.Label.html">pv.Label</a></li>
	
	<li><a href="../symbols/pv.Layout.grid.html">pv.Layout.grid</a></li>
	
	<li><a href="../symbols/pv.Layout.icicle.html">pv.Layout.icicle</a></li>
	
	<li><a href="../symbols/pv.Layout.stack.html">pv.Layout.stack</a></li>
	
	<li><a href="../symbols/pv.Layout.sunburst.html">pv.Layout.sunburst</a></li>
	
	<li><a href="../symbols/pv.Layout.treemap.html">pv.Layout.treemap</a></li>
	
	<li><a href="../symbols/pv.Line.html">pv.Line</a></li>
	
	<li><a href="../symbols/pv.Mark.html">pv.Mark</a></li>
	
	<li><a href="../symbols/pv.Nest.html">pv.Nest</a></li>
	
	<li><a href="../symbols/pv.ns.html">pv.ns</a></li>
	
	<li><a href="../symbols/pv.Panel.html">pv.Panel</a></li>
	
	<li><a href="../symbols/pv.Rule.html">pv.Rule</a></li>
	
	<li><a href="../symbols/pv.Scale.linear.html">pv.Scale.linear</a></li>
	
	<li><a href="../symbols/pv.Scale.log.html">pv.Scale.log</a></li>
	
	<li><a href="../symbols/pv.Scale.ordinal.html">pv.Scale.ordinal</a></li>
	
	<li><a href="../symbols/pv.Tree.html">pv.Tree</a></li>
	
	<li><a href="../symbols/pv.Vector.html">pv.Vector</a></li>
	
	<li><a href="../symbols/pv.version.html">pv.version</a></li>
	
	<li><a href="../symbols/pv.Wedge.html">pv.Wedge</a></li>
	
</ul>
<hr />
			<!-- end publish.classesIndex -->
		</div>
		
		<div id="content">
<!-- ============================== class title ============================ -->
			<h1 class="classTitle">
				
				Class pv.Scale.linear
			</h1>

<!-- ============================== class summary ========================== -->			
			<p class="description">
				
			
				Represents a linear scale. <style
type="text/css">sub{line-height:0}</style> <img src="../linear.png"
width="180" height="175" align="right"> Most commonly, a linear scale
represents a 1-dimensional linear transformation from a numeric domain of
input data [<i>d<sub>0</sub></i>, <i>d<sub>1</sub></i>] to a numeric range of
pixels [<i>r<sub>0</sub></i>, <i>r<sub>1</sub></i>]. The equation for such a
scale is:

<blockquote><i>f(x) = (x - d<sub>0</sub>) / (d<sub>1</sub> - d<sub>0</sub>) *
(r<sub>1</sub> - r<sub>0</sub>) + r<sub>0</sub></i></blockquote>

For example, a linear scale from the domain [0, 100] to range [0, 640]:

<blockquote><i>f(x) = (x - 0) / (100 - 0) * (640 - 0) + 0</i><br>
<i>f(x) = x / 100 * 640</i><br>
<i>f(x) = x * 6.4</i><br>
</blockquote>

Thus, saying

<pre>.height(function(d) d * 6.4)</pre>

is identical to

<pre>.height(pv.Scale.linear(0, 100).range(0, 640))</pre>

As you can see, scales do not always make code smaller, but they should make
code more explicit and easier to maintain. In addition to readability, scales
offer several useful features:

<p>1. The range can be expressed in colors, rather than pixels. Changing the
example above to

<pre>.fillStyle(pv.Scale.linear(0, 100).range("red", "green"))</pre>

will cause it to fill the marks "red" on an input value of 0, "green" on an
input value of 100, and some color in-between for intermediate values.

<p>2. The domain and range can be subdivided for a "poly-linear"
transformation. For example, you may want a diverging color scale that is
increasingly red for negative values, and increasingly green for positive
values:

<pre>.fillStyle(pv.Scale.linear(-1, 0, 1).range("red", "white", "green"))</pre>

The domain can be specified as a series of <i>n</i> monotonically-increasing
values; the range must also be specified as <i>n</i> values, resulting in
<i>n - 1</i> contiguous linear scales.

<p>3. Linear scales can be inverted for interaction. The <a href="#invert">#invert</a>
method takes a value in the output range, and returns the corresponding value
in the input domain. This is frequently used to convert the mouse location
(see <a href="../symbols/pv.Mark.html#mouse">pv.Mark#mouse</a>) to a value in the input domain. Note that
inversion is only supported for numeric ranges, and not colors.

<p>4. A scale can be queried for reasonable "tick" values. The <a href="#ticks">#ticks</a>
method provides a convenient way to get a series of evenly-spaced rounded
values in the input domain. Frequently these are used in conjunction with
<a href="../symbols/pv.Rule.html">pv.Rule</a> to display tick marks or grid lines.

<p>5. A scale can be "niced" to extend the domain to suitable rounded
numbers. If the minimum and maximum of the domain are messy because they are
derived from data, you can use <a href="#nice">#nice</a> to round these values down and
up to even numbers.
				
				
					<br /><i>Defined in: </i> <a href="../symbols/src/data_LinearScale.js.html">LinearScale.js</a>.
				
			</p>

<!-- ============================== constructor summary ==================== -->			
			
			<table class="summaryTable" cellspacing="0" summary="A summary of the constructor documented in the class pv.Scale.linear.">
				<caption>Class Summary</caption>
				<thead>
					<tr>
						<th scope="col">Constructor Attributes</th>
						<th scope="col">Constructor Name and Description</th>
					</tr>
				</thead>
				<tbody>
					<tr>
						<td class="attributes">&nbsp;</td>
						<td class="nameDescription" >
							<div class="fixedFont">
								<b><a href="../symbols/pv.Scale.linear.html#constructor">pv.Scale.linear</a></b>()
							</div>
							<div class="description">Returns a linear scale for the specified domain.</div>
						</td>
					</tr>
				</tbody>
			</table>
			

<!-- ============================== properties summary ===================== -->
			

<!-- ============================== methods summary ======================== -->
			
				
				
				<table class="summaryTable" cellspacing="0" summary="A summary of the methods documented in the class pv.Scale.linear.">
					<caption>Method Summary</caption>
					<thead>
						<tr>
							<th scope="col">Method Attributes</th>
							<th scope="col">Method Name and Description</th>
						</tr>
					</thead>
					<tbody>
					
						<tr>
							<td class="attributes">&nbsp;</td>
							<td class="nameDescription">
								<div class="fixedFont"><b><a href="../symbols/pv.Scale.linear.html#by">by</a></b>(f)
								</div>
								<div class="description">Returns a view of this scale by the specified accessor function <tt>f</tt>.</div>
							</td>
						</tr>
					
						<tr>
							<td class="attributes">&nbsp;</td>
							<td class="nameDescription">
								<div class="fixedFont"><b><a href="../symbols/pv.Scale.linear.html#domain">domain</a></b>()
								</div>
								<div class="description">Sets or gets the input domain.</div>
							</td>
						</tr>
					
						<tr>
							<td class="attributes">&nbsp;</td>
							<td class="nameDescription">
								<div class="fixedFont"><b><a href="../symbols/pv.Scale.linear.html#invert">invert</a></b>(y)
								</div>
								<div class="description">Inverts the specified value in the output range, returning the
corresponding value in the input domain.</div>
							</td>
						</tr>
					
						<tr>
							<td class="attributes">&nbsp;</td>
							<td class="nameDescription">
								<div class="fixedFont"><b><a href="../symbols/pv.Scale.linear.html#nice">nice</a></b>()
								</div>
								<div class="description">"Nices" this scale, extending the bounds of the input domain to
evenly-rounded values.</div>
							</td>
						</tr>
					
						<tr>
							<td class="attributes">&nbsp;</td>
							<td class="nameDescription">
								<div class="fixedFont"><b><a href="../symbols/pv.Scale.linear.html#range">range</a></b>()
								</div>
								<div class="description">Sets or gets the output range.</div>
							</td>
						</tr>
					
						<tr>
							<td class="attributes">&nbsp;</td>
							<td class="nameDescription">
								<div class="fixedFont"><b><a href="../symbols/pv.Scale.linear.html#tickFormat">tickFormat</a></b>(t)
								</div>
								<div class="description">Formats the specified tick value using the appropriate precision, based on
the step interval between tick marks.</div>
							</td>
						</tr>
					
						<tr>
							<td class="attributes">&nbsp;</td>
							<td class="nameDescription">
								<div class="fixedFont"><b><a href="../symbols/pv.Scale.linear.html#ticks">ticks</a></b>()
								</div>
								<div class="description">Returns an array of evenly-spaced, suitably-rounded values in the input
domain.</div>
							</td>
						</tr>
					
					</tbody>
				</table>
				
				
				
			
<!-- ============================== events summary ======================== -->
			

<!-- ============================== constructor details ==================== -->		
			
			<div class="details"><a name="constructor"> </a>
				<div class="sectionTitle">
					Class Detail
				</div>
				
				<div class="fixedFont">
						<b>pv.Scale.linear</b>()
				</div>
				
				<div class="description">
					Returns a linear scale for the specified domain. The arguments to this
constructor are optional, and equivalent to calling <a href="#domain">#domain</a>.
					
				</div>
				
				
				
				
					
						<dl class="detailList">
						<dt class="heading">Parameters:</dt>
						
							<dt>
								<span class="light fixedFont">{number...}</span>  <b>domain...</b>
								
							</dt>
								<dd>domain values.</dd>
						
						</dl>
					
					
					
					
					
						<dl class="detailList">
						<dt class="heading">Returns:</dt>
						
								<dd><span class="light fixedFont">{<a href="../symbols/pv.Scale.linear.html">pv.Scale.linear</a>}</span> a linear scale.</dd>
						
						</dl>
					
					
					

			</div>
			

<!-- ============================== field details ========================== -->		
			

<!-- ============================== method details ========================= -->		
			
				<div class="sectionTitle">
					Method Detail
				</div>
				
					<a name="by"> </a>
					<div class="fixedFont">
					
					<span class="light">{<a href="../symbols/pv.Scale.linear.html">pv.Scale.linear</a>}</span>
					<b>by</b>(f)
					
					</div>
					<div class="description">
						Returns a view of this scale by the specified accessor function <tt>f</tt>.
Given a scale <tt>y</tt>, <tt>y.by(function(d) d.foo)</tt> is equivalent to
<tt>function(d) y(d.foo)</tt>.

<p>This method is provided for convenience, such that scales can be
succinctly defined inline. For example, given an array of data elements
that have a <tt>score</tt> attribute with the domain [0, 1], the height
property could be specified as:

<pre>.height(pv.Scale.linear().range(0, 480).by(function(d) d.score))</pre>

This is equivalent to:

<pre>.height(function(d) d.score * 480)</pre>

This method should be used judiciously; it is typically more clear to
invoke the scale directly, passing in the value to be scaled.
						
						
					</div>
					
					
					
						
							<dl class="detailList">
							<dt class="heading">Parameters:</dt>
							
								<dt>
									<span class="light fixedFont">{function}</span> <b>f</b>
									
								</dt>
								<dd>an accessor function.</dd>
							
							</dl>
						
						
						
						
						
							<dl class="detailList">
							<dt class="heading">Returns:</dt>
							
								<dd><span class="light fixedFont">{<a href="../symbols/pv.Scale.linear.html">pv.Scale.linear</a>}</span> a view of this scale by the specified accessor
function.</dd>
							
							</dl>
						
						
						

					<hr />
				
					<a name="domain"> </a>
					<div class="fixedFont">
					
					<span class="light">{<a href="../symbols/pv.Scale.linear.html">pv.Scale.linear</a>}</span>
					<b>domain</b>()
					
					</div>
					<div class="description">
						Sets or gets the input domain. This method can be invoked several ways:

<p>1. <tt>domain(min, ..., max)</tt>

<p>Specifying the domain as a series of numbers is the most explicit and
recommended approach. Most commonly, two numbers are specified: the minimum
and maximum value. However, for a diverging scale, or other subdivided
poly-linear scales, multiple values can be specified. Values can be derived
from data using <a href="../symbols/pv.html#.min">pv.min</a> and <a href="../symbols/pv.html#.max">pv.max</a>. For example:

<pre>.domain(0, pv.max(array))</pre>

An alternative method for deriving minimum and maximum values from data
follows.

<p>2. <tt>domain(array, minf, maxf)</tt>

<p>When both the minimum and maximum value are derived from data, the
arguments to the <tt>domain</tt> method can be specified as the array of
data, followed by zero, one or two accessor functions. For example, if the
array of data is just an array of numbers:

<pre>.domain(array)</pre>

On the other hand, if the array elements are objects representing stock
values per day, and the domain should consider the stock's daily low and
daily high:

<pre>.domain(array, function(d) d.low, function(d) d.high)</pre>

The first method of setting the domain is preferred because it is more
explicit; setting the domain using this second method should be used only
if brevity is required.

<p>3. <tt>domain()</tt>

<p>Invoking the <tt>domain</tt> method with no arguments returns the
current domain as an array of numbers.
						
						
					</div>
					
					
					
						
							<dl class="detailList">
							<dt class="heading">Parameters:</dt>
							
								<dt>
									<span class="light fixedFont">{number...}</span> <b>domain...</b>
									
								</dt>
								<dd>domain values.</dd>
							
							</dl>
						
						
						
						
						
							<dl class="detailList">
							<dt class="heading">Returns:</dt>
							
								<dd><span class="light fixedFont">{<a href="../symbols/pv.Scale.linear.html">pv.Scale.linear</a>}</span> <tt>this</tt>, or the current domain.</dd>
							
							</dl>
						
						
						

					<hr />
				
					<a name="invert"> </a>
					<div class="fixedFont">
					
					<span class="light">{number}</span>
					<b>invert</b>(y)
					
					</div>
					<div class="description">
						Inverts the specified value in the output range, returning the
corresponding value in the input domain. This is frequently used to convert
the mouse location (see <a href="../symbols/pv.Mark.html#mouse">pv.Mark#mouse</a>) to a value in the input
domain. Inversion is only supported for numeric ranges, and not colors.

<p>Note that this method does not do any rounding or bounds checking. If
the input domain is discrete (e.g., an array index), the returned value
should be rounded. If the specified <tt>y</tt> value is outside the range,
the returned value may be equivalently outside the input domain.
						
						
					</div>
					
					
					
						
							<dl class="detailList">
							<dt class="heading">Parameters:</dt>
							
								<dt>
									<span class="light fixedFont">{number}</span> <b>y</b>
									
								</dt>
								<dd>a value in the output range (a pixel location).</dd>
							
							</dl>
						
						
						
						
						
							<dl class="detailList">
							<dt class="heading">Returns:</dt>
							
								<dd><span class="light fixedFont">{number}</span> a value in the input domain.</dd>
							
							</dl>
						
						
						

					<hr />
				
					<a name="nice"> </a>
					<div class="fixedFont">
					
					<span class="light">{<a href="../symbols/pv.Scale.linear.html">pv.Scale.linear</a>}</span>
					<b>nice</b>()
					
					</div>
					<div class="description">
						"Nices" this scale, extending the bounds of the input domain to
evenly-rounded values. Nicing is useful if the domain is computed
dynamically from data, and may be irregular. For example, given a domain of
[0.20147987687960267, 0.996679553296417], a call to <tt>nice()</tt> might
extend the domain to [0.2, 1].

<p>This method must be invoked each time after setting the domain.
						
						
					</div>
					
					
					
						
						
						
						
						
							<dl class="detailList">
							<dt class="heading">Returns:</dt>
							
								<dd><span class="light fixedFont">{<a href="../symbols/pv.Scale.linear.html">pv.Scale.linear</a>}</span> <tt>this</tt>.</dd>
							
							</dl>
						
						
						

					<hr />
				
					<a name="range"> </a>
					<div class="fixedFont">
					
					<span class="light">{<a href="../symbols/pv.Scale.linear.html">pv.Scale.linear</a>}</span>
					<b>range</b>()
					
					</div>
					<div class="description">
						Sets or gets the output range. This method can be invoked several ways:

<p>1. <tt>range(min, ..., max)</tt>

<p>The range may be specified as a series of numbers or colors. Most
commonly, two numbers are specified: the minimum and maximum pixel values.
For a color scale, values may be specified as <a href="../symbols/pv.Color.html">pv.Color</a>s or
equivalent strings. For a diverging scale, or other subdivided poly-linear
scales, multiple values can be specified. For example:

<pre>.range("red", "white", "green")</pre>

<p>Currently, only numbers and colors are supported as range values. The
number of range values must exactly match the number of domain values, or
the behavior of the scale is undefined.

<p>2. <tt>range()</tt>

<p>Invoking the <tt>range</tt> method with no arguments returns the current
range as an array of numbers or colors.
						
						
					</div>
					
					
					
						
							<dl class="detailList">
							<dt class="heading">Parameters:</dt>
							
								<dt>
									<span class="light fixedFont">{...}</span> <b>range...</b>
									
								</dt>
								<dd>range values.</dd>
							
							</dl>
						
						
						
						
						
							<dl class="detailList">
							<dt class="heading">Returns:</dt>
							
								<dd><span class="light fixedFont">{<a href="../symbols/pv.Scale.linear.html">pv.Scale.linear</a>}</span> <tt>this</tt>, or the current range.</dd>
							
							</dl>
						
						
						

					<hr />
				
					<a name="tickFormat"> </a>
					<div class="fixedFont">
					
					<span class="light">{string}</span>
					<b>tickFormat</b>(t)
					
					</div>
					<div class="description">
						Formats the specified tick value using the appropriate precision, based on
the step interval between tick marks.
						
						
					</div>
					
					
					
						
							<dl class="detailList">
							<dt class="heading">Parameters:</dt>
							
								<dt>
									<span class="light fixedFont">{number}</span> <b>t</b>
									
								</dt>
								<dd>a tick value.</dd>
							
							</dl>
						
						
						
						
						
							<dl class="detailList">
							<dt class="heading">Returns:</dt>
							
								<dd><span class="light fixedFont">{string}</span> a formatted tick value.</dd>
							
							</dl>
						
						
						

					<hr />
				
					<a name="ticks"> </a>
					<div class="fixedFont">
					
					<span class="light">{number[]}</span>
					<b>ticks</b>()
					
					</div>
					<div class="description">
						Returns an array of evenly-spaced, suitably-rounded values in the input
domain. This method attempts to return between 5 and 10 tick values. These
values are frequently used in conjunction with <a href="../symbols/pv.Rule.html">pv.Rule</a> to display
tick marks or grid lines.
						
						
					</div>
					
					
					
						
						
						
						
						
							<dl class="detailList">
							<dt class="heading">Returns:</dt>
							
								<dd><span class="light fixedFont">{number[]}</span> an array input domain values to use as ticks.</dd>
							
							</dl>
						
						
						

					
				
			
			
<!-- ============================== event details ========================= -->		
			
			
			<hr />
		</div>

		
<!-- ============================== footer ================================= -->
		<div class="fineprint" style="clear:both">
			
			Documentation generated by <a href="http://code.google.com/p/jsdoc-toolkit/" target="_blank">JsDoc Toolkit</a> 2.3.0 on Tue Oct 06 2009 09:59:02 GMT-0700 (PDT)
		</div>
	</body>
</html>
